\documentclass[Orbiter Developer Manual.tex]{subfiles}
\begin{document}

\section{Graphics Client Development}

\subsection{Introduction}
This page contains information for developers of plug-in graphics clients for the non-graphics version of Orbiter (Orbiter\_NG).\\
Graphics clients are DLL modules which contain the implementation of a client class derived from oapi::GraphicsClient. They handle the device-specific aspects of rendering a 3-D window into the "Orbiter world".


\subsection{Particle Streams}
Particle streams are a component of Orbiter graphics clients.\\
Particle streams can be used to create visual effects for contrails, exhaust and plasma streams, reentry heating, condensation, etc. The management of particle streams is almost entirely the responsibility of the graphics client. The orbiter core notifies the client only
\begin{itemize}
\item to request a new particle stream for a vessel object
\item to detach a stream from its object (e.g. if the object is deleted)
\end{itemize}

\noindent
The implementation details for the particle streams, including render options, are left to the client.


\subsubsection{Adding particle stream support}

To add particle stream support to a graphics client, the following steps are required:
\begin{itemize}
\item Create one or more classes derived from oapi::ParticleStream
\item Overload the particle stream-related callback methods of oapi::GraphicsClient, including
\begin{itemize}
\item oapi::GraphicsClient::clbkCreateParticleStream()
\item oapi::GraphicsClient::clbkCreateExhaustStream()
\item oapi::GraphicsClient::clbkCreateReentryStream()
\end{itemize}
\end{itemize}

\noindent
By default, these methods return NULL pointers, i.e. don't provide particle stream support. Your overloaded methods should create an instance of an appropriate derived particle stream class and return a pointer to it.

\alertbox{The client must keep track of all particle streams created. In particular, the orbiter core never deletes any particle streams it has obtained from the client. Particle stream management and cleanup must be provided by the client.}


\subsubsection{Attaching and detaching streams}
Once a particle stream has been created, it must be connected to a vessel instance (provided by the hVessel parameter in each of the particle stream-related callback functions of the graphics client). To connect the particle stream to the vessel, use one of the oapi::ParticleStream::Attach() methods using the provided vessel handle.\\
The particle emission point and emission direction are relative to the associated vessel.\\
Sometimes Orbiter will call the oapi::ParticleStream::Detach() method for a stream. This is usually in response to deletion of the vessel. Therefore, the stream should no longer make use of the vessel reference after it has been detached. In particular, no new particles should be generated.

\infobox{After Orbiter has detached a particle stream, it will no longer access it. The client is free to delete the particle stream instance once it has been detached. Generally, the stream should be deleted after all the remaining particles in the stream have expired.}


\subsubsection{Deleting streams}
Generally, streams should only be deleted after they have been detached and after all remaining particles have expired. Deleting a stream with active particles will create a visual inconsistency and should be avoided. The only exception is the cleanup at the end of a simulation session.\\
When a stream is deleted while still attached to its object, Orbiter will call the stream's Detach method during the destruction process.

\end{document}
